Web.Config Transforms in .Net Core

Within .Net Core we can set the ASPNETCORE_ENVIRONMENT inside our web.config files.

The ASPNETCORE_ENVIRONMENT can have any value but by convention we tend to use:

Development
Stating
Productiuon

By changing the ASPNETCORE_ENVIRONMENT we can run different code in differen environments. For example you may want to bundle and minify your JS files in prodcution, but use the original files within the development environment:

@* JS files that are used in the layout files *@
<environment include="Development">
    <script src="~/lib/jquery/dist/jquery.js"></script>
    <script src="~/lib/jquery-ui/jquery-ui.min.js"></script>
    <script src="~/lib/bootstrap/dist/js/bootstrap.js"></script>
    <script src="~/lib/knockout/knockout.js"></script>
</environment>
<environment exclude="Development">
    <script src="~/js/bundle.min.js" asp-append-version="true" ></script>
</environment>

To set the ASPNETCORE_ENVIRONMENT for different environments you can create additional web.config environment files, and use the web.config transformation functionality to transform the web.config file for each environment.

e.g. web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" stdoutLogEnabled="false" stdoutLogFile=".\logs\">
      <environmentVariables>
        <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
      </environmentVariables>
    </aspNetCore>

    <!-- Removed for brevity -->
    
  </system.webServer>
</configuration>

e.g. web.release.config

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

  <system.webServer>
    <aspNetCore>
      <environmentVariables>
        <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
  
</configuration>

Unfortunately, when we publish the site .Net Core does not support the transformations, and we have to add an additional NuGet package in to do it:

Add the following reference in your project file:

<ItemGroup>
    <DotNetCliToolReference Include="Microsoft.DotNet.Xdt.Tools" Version="2.0.0" />
</ItemGroup>

Note - when I tried to add this via the ‘Manage NuGet packages…’ I got the following error:

Package ‘Microsoft.DotNet.Xdt.Tools 2.0.0’ has a package type ‘DotnetCliTool’ that is not supported by project…

The following link suggests adding the reference directly into the project file like we did as a work around:

https://github.com/NuGet/Home/issues/4190

Finally you will need to add the following just before the closing tag:

<Target Name="ApplyXdtConfigTransform" BeforeTargets="_TransformWebConfig">
   <PropertyGroup>
     <_SourceWebConfig>$(MSBuildThisFileDirectory)Web.config</_SourceWebConfig>
     <_XdtTransform>$(MSBuildThisFileDirectory)Web.$(Configuration).config</_XdtTransform>
     <_TargetWebConfig>$(PublishDir)Web.config</_TargetWebConfig>
   </PropertyGroup>
   <Exec Command="dotnet transform-xdt --xml &quot;$(_SourceWebConfig)&quot; --transform &quot;$(_XdtTransform)&quot; --output &quot;$(_TargetWebConfig)&quot;" Condition="Exists('$(_XdtTransform)')" />
< /Target>

Now when you publish your site, the ASPNETCORE_ENVIRONMENT should be correctly transformed in the web.config file.